Style Content

DingiSource is an abstract base class for map content sources. A map content source supplies content to be shown on the map. A source is added to an DingiStyle object along with an DingiForegroundStyleLayer object. The foreground style layer defines the appearance of any content supplied by the source.

Each source defined by the style JSON file is represented at runtime by an DingiSource object that you can use to refine the map’s content. You can also add and remove sources dynamically using methods such as -[DingiStyle addSource:] and -[DingiStyle sourceWithIdentifier:].

Create instances of DingiShapeSource, DingiComputedShapeSource, DingiImageSource, and the concrete subclasses of DingiTileSource (DingiVectorTileSource and DingiRasterTileSource) in order to use DingiSource’s properties and methods. Do not create instances of DingiSource directly, and do not create your own subclasses of this class.

DingiShapeSource is a map content source that supplies vector shapes to be shown on the map. The shapes may be instances of MGLShape or DingiFeature, or they may be defined by local or external GeoJSON code. A shape source is added to an DingiStyle object along with an DingiVectorStyleLayer object. The vector style layer defines the appearance of any content supplied by the shape source. You can update a shape source by setting its shape or URL property.

DingiShapeSource is optimized for data sets that change dynamically and fit completely in memory. For large data sets that do not fit completely in memory, use the DingiComputedShapeSource or DingiVectorTileSource class.

Each geojson source defined by the style JSON file is represented at runtime by an DingiShapeSource object that you can use to refine the map’s content and initialize new style layers. You can also add and remove sources dynamically using methods such as -[DingiStyle addSource:] and -[DingiStyle sourceWithIdentifier:].

Any vector style layer initialized with a shape source should have a nil value in its sourceLayerIdentifier property.

Example

var coordinates: [CLLocationCoordinate2D] = [
    CLLocationCoordinate2D(latitude: 37.77, longitude: -122.42),
    CLLocationCoordinate2D(latitude: 38.91, longitude: -77.04),
]
let polyline = DingiPolylineFeature(coordinates: &coordinates, count: UInt(coordinates.count))
let source = DingiShapeSource(identifier: "lines", features: [polyline], options: nil)
mapView.style?.addSource(source)

DingiComputedShapeSource is a map content source that supplies vector shapes, one tile at a time, to be shown on the map on demand. You implement a class conforming to the DingiComputedShapeSourceDataSource protocol that returns instances of DingiShape or DingiFeature, then add a computed shape source to an DingiStyle object along with an DingiVectorStyleLayer object. The vector style layer defines the appearance of any content supplied by the computed shape source.

DingiComputedShapeSource is similar to DingiShapeSource but is optimized for data sets that change dynamically or are too large to fit completely in memory. It is also useful for data that is divided into tiles in a format other than Mapbox Vector Tiles. For GeoJSON data, use the DingiShapeSource class. For static tiles or Mapbox Vector Tiles, use the DingiVectorTileSource class.

You can add and remove sources dynamically using methods such as -[DingiStyle addSource:] and -[DingiStyle sourceWithIdentifier:]. This class cannot be represented in a style JSON file; you must add it ot the style at runtime.

DingiTileSource is a map content source that supplies map tiles to be shown on the map. The location of and metadata about the tiles are defined either by an option dictionary or by an external file that conforms to the TileJSON specification. A tile source is added to an DingiStyle object along with one or more DingiRasterStyleLayer or DingiVectorStyleLayer objects. Use a style layer to control the appearance of content supplied by the tile source.

A tile source is also known as a tile set. To learn about the structure of a Mapbox-hosted tile set, view it in Mapbox Studio’s Tilesets editor.

Create instances of DingiRasterTileSource and DingiVectorTileSource in order to use DingiTileSource‘s properties and methods. Do not create instances of DingiTileSource directly, and do not create your own subclasses of this class.

DingiRasterTileSource is a map content source that supplies raster image tiles to be shown on the map. The location of and metadata about the tiles are defined either by an option dictionary or by an external file that conforms to the TileJSON specification. A raster tile source is added to an DingiStyle object along with one or more DingiRasterStyleLayer objects. Use a raster style layer to control the appearance of content supplied by the raster tile source.

Each raster source defined by the style JSON file is represented at runtime by an DingiRasterTileSource object that you can use to initialize new style layers. You can also add and remove sources dynamically using methods such as -[DingiStyle addSource:] and -[DingiStyle sourceWithIdentifier:].

Example

let source = DingiRasterTileSource(identifier: "clouds", tileURLTemplates: ["https://example.com/raster-tiles/{z}/{x}/{y}.png"], options: [
    .minimumZoomLevel: 9,
    .maximumZoomLevel: 16,
    .tileSize: 512,
    .attributionInfos: [
        DingiAttributionInfo(title: NSAttributedString(string: "© Mapbox"), url: URL(string: "https://mapbox.com"))
    ]
])
mapView.style?.addSource(source)

DingiRasterDEMSource is a map content source that supplies rasterized digital elevation model (DEM) tiles to be shown on the map. The location of and metadata about the tiles are defined either by an option dictionary or by an external file that conforms to the TileJSON specification. A raster DEM source is added to an DingiStyle object along with one or more DingiHillshadeStyleLayer objects. Use a hillshade style layer to control the appearance of content supplied by the raster DEM source.

Each raster-dem source defined by the style JSON file is represented at runtime by an DingiRasterDEMSource object that you can use to initialize new style layers. You can also add and remove sources dynamically using methods such as -[DingiStyle addSource:] and -[DingiStyle sourceWithIdentifier:].

Currently, raster DEM sources only support the format used by Mapbox Terrain-RGB.

Example

let terrainRGBURL = URL(string: "mapbox://mapbox.terrain-rgb")!
let source = DingiRasterDEMSource(identifier: "hills", configurationURL: terrainRGBURL)
mapView.style?.addSource(source)

DingiVectorTileSource is a map content source that supplies tiled vector data in Mapbox Vector Tile format to be shown on the map. The location of and metadata about the tiles are defined either by an option dictionary or by an external file that conforms to the TileJSON specification. A vector tile source is added to an DingiStyle object along with one or more DingiVectorStyleLayer objects. A vector style layer defines the appearance of any content supplied by the vector tile source.

DingiVectorTileSource is optimized for data sets that are too large to fit completely in memory, such as vector tile sets or data sets managed in Mapbox Studio. For GeoJSON data, use the DingiShapeSource class. For tiled data that changes dynamically, the DingiComputedShapeSource class may be a suitable alternative.

Each vector source defined by the style JSON file is represented at runtime by an DingiVectorTileSource object that you can use to initialize new style layers. You can also add and remove sources dynamically using methods such as -[DingiStyle addSource:] and -[DingiStyle sourceWithIdentifier:].

Within each vector tile, each geometric coordinate must lie between −1 × extent and (extent × 2) − 1, inclusive. Any vector style layer initialized with a vector tile source must have a non-nil value in its sourceLayerIdentifier property.

Commonly used vector tile sources include Mapbox Streets, Mapbox Terrain, and Mapbox Traffic.

Example

let source = DingiVectorTileSource(identifier: "pois", tileURLTemplates: ["https://example.com/vector-tiles/{z}/{x}/{y}.mvt"], options: [
    .minimumZoomLevel: 9,
    .maximumZoomLevel: 16,
    .attributionInfos: [
        DingiAttributionInfo(title: NSAttributedString(string: "© Mapbox"), url: URL(string: "https://mapbox.com"))
    ]
])
mapView.style?.addSource(source)

DingiImageSource is a content source that is used for a georeferenced raster image to be shown on the map. The georeferenced image scales and rotates as the user zooms and rotates the map. Images may also be used as icons or patterns in a style layer. To register an image for use as an icon or pattern, use the -[DingiStyle setImage:forName:] method. To configure a point annotation’s image, use the DingiAnnotationImage class.

The geographic location of the raster image content, supplied with DingiCoordinateQuad, can be non-axis aligned. DingiImageSource supports raster content from NSURL, NSImage (macOS), or UIImage (iOS). An image source is added to an DingiStyle object along with one or more DingiRasterStyleLayer objects. Use a raster style layer to control the appearance of content supplied by the image source.

Each image source defined by the style JSON file is represented at runtime by an DingiImageSource object that you can use to initialize new style layers. You can also add and remove sources dynamically using methods such as -[DingiStyle addSource:] and -[DingiStyle sourceWithIdentifier:].

Example

let coordinates = DingiCoordinateQuad(
  topLeft: CLLocationCoordinate2D(latitude: 46.437, longitude: -80.425),
  bottomLeft: CLLocationCoordinate2D(latitude: 37.936, longitude: -80.425),
  bottomRight: CLLocationCoordinate2D(latitude: 37.936, longitude: -71.516),
  topRight: CLLocationCoordinate2D(latitude: 46.437, longitude: -71.516))
let source = DingiImageSource(identifier: "radar", coordinateQuad: coordinates, url: URL(string: "https://www.mapbox.com/mapbox-gl-js/assets/radar.gif")!)
mapView.style?.addSource(source)